|
|
EmbedControl |
||||
| Header: | Controls.h | Carbon status: | Supported | |
Embeds one control inside another.
OSErr EmbedControl (
ControlRef inControl,
ControlRef inContainer
);
A handle to the control to be embedded.
A handle to the embedder control.
A result code.
Establishing an embedding hierarchy can be accomplished in two steps: creating a root control and embedding controls within it.
To embed controls in a window, you must create a root control for that window. The root control is the container for all other window controls. You create the root control in one of two ways—by calling the CreateRootControl function or by setting the appropriate dialog flag. The root control can be retrieved by calling GetRootControl.
The root control is implemented as a user pane control. You can attach any application-defined user pane functions to the root control to perform actions such as hit testing, drawing, handling keyboard focus, erasing to the correct background, and processing idle and keyboard events. For information on how to write these functions.
Once you have created a root control, newly created controls will automatically be embedded in the root control when you call NewControl or GetNewControl. You can specify that a specific control be embedded into another by calling EmbedControl.
Note that an embedding hierarchy must be established before your application calls the EmbedControl function. If the specified control does not support embedding or there is no root control in the owning window, an error is returned. If the control you wish to embed is in a different window from the embedder control, an error is returned.
By acting on an embedder control, you can move, disable, or hide groups of items. For example, you can use a blank user pane control as the embedder control for all items in a particular “page” of a tab control. After creating as many user panes as you have tabs, you can hide one and show the next when a tab is clicked. All the controls embedded in the user pane will be hidden and shown automatically when the user pane is hidden and shown.
The Dialog Manager uses AutoEmbedControl to position dialog items in an embedding hierarchy based on both visual containment and the item list resource order. As items are added to a dialog box during creation, controls that already exist in the window will be containers for new controls if they both visually contain the control and have set the kControlSupportsEmbedding feature bit. For this reason, you should place the largest embedder controls at the beginning of the item list resource. As an example, the Dialog Manager would embed radio buttons in a tab control if they visually “fit” inside the tab control, as long as the tab control was already created in a 'DITL' resource and established as an embedder control.
In addition to calling CreateRootControl, you can establish an embedding hierarchy in a dialog box by either setting the feature bit kDialogFlagsUseControlHierarchy in the extended dialog resource or passing it in the inFlags parameter of the Dialog Manager function NewFeaturesDialog. An embedding hierarchy can be created in an alert box by setting the kAlertFlagsUseControlHierarchy bit in the extended alert resource. It is important to note that a preexisting alert or dialog item will become a control if it is in an alert or dialog box that now uses an embedding hierarchy.
The embedding hierarchy enforces drawing order by drawing the embedding control before its embedded controls. Using an embedding hierarchy also enforces orderly hit-testing, since it performs an “inside-out” hit test to determine the most deeply nested control that is hit by the mouse. An embedding hierarchy is also necessary for controls to make use of keyboard focus, the default focusing order for which is a linear progression that uses the order the controls were added to the window. For more details on keyboard focus, see “Handling Keyboard Focus”.
This function is available with Appearance Manager 1.0 and later.
Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.
© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)